Add Server Streamable Http Transport #235

zshea · 2025-08-25T08:37:41Z

Implement server StreamableHttpTransport (both stateful and stateless)
This is a workable solution, tested with Claude Code

Caveat:

The Ktor server SSE plugin only supports the GET method. Even if I hacked the routing to support the POST method, it behaves weirdly (see additional context). In this PR, the StreamableHttpTransport always works with enableJsonResponse = true. We can remove this limitation once the upstream has fixed this issue.
Because of the above issue, I can't write an integration test for this transport. The client StreamHttpTransport assumes the SSE stream while the server assumes the JSON response.
I didn't update the documentation, hope this PR won't have significant changes. I'll update the documentation after this PR is merged.

Motivation and Context

It is painful to support /sse + /message endpoint on production. Hopefully we can close this issue with this PR.

How Has This Been Tested?

It has been tested in my environment with Claude Code (1.0.89) MCP with both mcpStreamableHttp and mcpStatelessStreamableHttp

Breaking Changes

No, everything is backward compatible

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Ktor server SSE plugin with POST method
It is workable with the following implementation:

route("/sse", HttpMethod.POST) {
    sse {
        call.response.status(HttpStatusCode.NotAcceptable)
        send(event = "message", data = "1")
    }
}

But the response is always 200, even if we set the status explicitly. And the connection won't be closed with a 4xx or 5xx response. It breaks the MCP spec and can't be used directly. I think we need to create issues to upstream.

Thanks @SeanChinJunKai and @devcrocod 's work on Add Streamable Http Transport #87. I got some insights there and created this PR.

zshea · 2025-08-25T08:41:10Z

Hi @e5l @devcrocod @SeanChinJunKai , would you mind taking a look?

zshea · 2025-09-10T00:20:07Z

Hi @devcrocod , would you mind taking a look when available?

kpavlov

Thank you @zshea for the PR
Would it be possible to add integration tests to make sure it actually works?
Also, id is mandatory for JSONRPCRequest, JSONRPCResponse, so let's keep it non-nullable

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types.kt

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/KtorServer.kt

dvilker

I tried your PR in practice in Stateless mode and brought back what I found.

...commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt

dvilker · 2025-09-22T13:34:15Z

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/KtorServer.kt

+    block: RoutingContext.() -> Server,
+) {
+    routing {
+        post("/mcp") {


get requests also need to be processed.

I didn't implement because it's not needed for json response. Once we add SSE back, we can do it then.

I didn't implement because it's not needed for json response. Once we add SSE back, we can do it then.

https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http

The server MUST either return Content-Type: text/event-stream in response to this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server does not offer an SSE stream at this endpoint

Without processing (which responds with code 405), it seems the inspector was spamming errors.

I replaced post(... with route(".... Everything else has already been implemented by you.

mantisMolloy · 2025-10-02T22:44:12Z

Hi @zshea

Thanks for this PR.

In relation to:

But the response is always 200, even if we set the status explicitly. And the connection won't be closed with a 4xx or 5xx response. It breaks the MCP spec and can't be used directly. I think we need to create issues to upstream.

Was an issue created on ktor for this?

mantisMolloy · 2025-10-03T22:46:09Z

One thing that's not clear to me

I can't write an integration test for this transport. The client StreamHttpTransport assumes the SSE stream while the server assumes the JSON response.

Looking at the spec the client MUST be able to accept a json response. Is this a bug in the client?

From the spec:

If the input contains any number of JSON-RPC requests, the server MUST either return Content-Type: text/event-stream, to initiate an SSE stream, or Content-Type: application/json, to return one JSON object. The client MUST support both these cases.

mantisMolloy · 2025-10-05T13:33:40Z

I played around with this a bit.

When using enableJsonResponse = true the client StreamHttpTransport works when you add a sse route for get requests using the ktor plugin. Just pass the session into the the server StreamHttpTransport and then the it will return a 406 status and this overcomes the issue where the client assumes the SSE stream. We should be able to add integration tests if the sse route is added.
I'm not sure if a fix is required upstream for the ktor routing plugin. Could we implement a version of io.ktor.server.sse.ServerSSESession and initiate the event stream inside handlePostRequest when enableJsonResponse = false.

zshea · 2025-10-29T15:32:57Z

Hi @zshea

Thanks for this PR.

In relation to:

But the response is always 200, even if we set the status explicitly. And the connection won't be closed with a 4xx or 5xx response. It breaks the MCP spec and can't be used directly. I think we need to create issues to upstream.

Was an issue created on ktor for this?

I found an answer here: https://youtrack.jetbrains.com/issue/KTOR-8327/SSE-Document-how-to-receive-SSE-requests-with-POST-and-other-methods#focus=Comments-27-12594500.0-0

The workaround significantly changes the architectureof how we implement transport: need to split header response and body response.

zshea · 2025-10-29T15:34:16Z

Thank you @zshea for the PR Would it be possible to add integration tests to make sure it actually works?

TBH I've been struggling with adding tests here, would appreciate some help here, or I can dive more later. Sorry almost forgot this PR for a while...

zshea mentioned this pull request Aug 25, 2025

Add Streamable Http Transport #87

Closed

9 tasks

e5l requested a review from devcrocod August 28, 2025 06:49

kpavlov force-pushed the zshea/streamable-http branch from 6820649 to 465f3dd Compare September 16, 2025 08:51

kpavlov requested changes Sep 16, 2025

View reviewed changes

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types.kt Outdated Show resolved Hide resolved

kpavlov reviewed Sep 16, 2025

View reviewed changes

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/KtorServer.kt Show resolved Hide resolved

dvilker reviewed Sep 22, 2025

View reviewed changes

mantisMolloy mentioned this pull request Oct 5, 2025

Adding Streaming HTTP Transport #79

Open

devcrocod mentioned this pull request Oct 28, 2025

Brothers, when will the Kotlin SDK support Streamable HTTP? #346

Open

zshea added 2 commits October 29, 2025 22:20

Add Streamable Http Transport

cfc188e

update from comments

b01e472

zshea force-pushed the zshea/streamable-http branch from 465f3dd to b01e472 Compare October 29, 2025 15:24

kdoc

835e45e

Add Server Streamable Http Transport #235

Are you sure you want to change the base?

Add Server Streamable Http Transport #235

Conversation

zshea commented Aug 25, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

zshea commented Aug 25, 2025

Uh oh!

zshea commented Sep 10, 2025

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dvilker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dvilker Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

zshea Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

dvilker Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mantisMolloy commented Oct 2, 2025

Uh oh!

mantisMolloy commented Oct 3, 2025

Uh oh!

mantisMolloy commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zshea commented Oct 29, 2025

Uh oh!

zshea commented Oct 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dvilker Oct 29, 2025 •

edited

Loading

mantisMolloy commented Oct 5, 2025 •

edited

Loading